nice_things/macros/class.macro.sh

These macros allow you to declare classes and create objects. Objects provide long-lived state and accompanying behavior that enable the creation of complex types.

Note

Classes in this framework are not meant to introduce an object-oriented programming paradigm. Instead, they were born from a simple need to have local state that can survive recursion, which is not easily achievable in POSIX sh due to the lack of local variables. In the end, this object system provides a little more than just that.

class

Since 0.3.0 · Source

Synopsis
#{{{ class <Name> "{ <field>… }" }}}

Configuration
–

Description
Declare a class, giving it a name and fields.

Class names MUST be written in UpperCamelCase form. In public modules, it should have the leading namespace prefix NS__ as usual.

Four private methods are created automatically: <Name>_constructor_, <Name>_destructor_, <Name>_get_, <Name>_set_.

• <Name>_constructor_ <&self> [<field> <value>]…: Create an object and initialize all fields. Optional field-value pairs can be passed as arguments to initialize fields to specific values. Fields not provided in this form will be initialized to null.
• <Name>_destructor_ <&self>: Destroy the object and clear all fields.
• <Name>_get_ <&self> [<out_var> <field>]…: Read values from fields into variables.
• <Name>_set_ <&self> [<field> <value>]…: Assign values to fields.

Options
–

Operands

• <Name>: Name of the class. MUST be written in UpperCamelCase form. Can contain namespace prefix.
• <field>: A field of the objects of this class.

Stdin
–

Stdout
Renders the fields and methods of the class, and imports the module at nice_things/type/class.sh for the necessary support functions.

Stderr
log_error.

Exit status

• 0: Successful completion.
• 1: Bad declaration (abort).

Abort
Any failure will abort the build process. No runtime abort is added.

Usage examples

#{{{
class NS__Array "{
	length,
	slot_l,
	slot_r
}"
#}}}

class_shift

Since 0.3.0 · Source

Synopsis
#{{{ class_shift [<amount>] }}}

Configuration
–

Description
Shift positional parameters skipping the first.

Works just like the shift shell special builtin utility, but skips shifting parameter $1. For use in class methods, since the first parameter is the self reference <&self>, and keeping it in a positional parameter instead of assigning to a variable is required sometimes, because variables are global, and positional parameters is the only local state available in POSIX sh.

Warning

This macro is only safe to use when the first parameter is an object reference. No runtime quoting or escaping of the value in $1 is attempted for performance reasons.

Options
–

Operands
<amount>: Number of parameters to shift. Defaults to 1 if not provided. Can be the name of a runtime variable containing the number.

Stdin
–

Stdout
One line of code is printed.

Stderr
–

Exit status
0: Successful completion.

Abort
–

Usage examples

# Shift positional parameters by 1
#{{{ class_shift }}}

# Shift using dynamic runtime value
NS__shifts=2
#{{{ class_shift NS__shifts }}}

new

Since 0.3.0 · Source

Synopsis
<out_var>=#{{{ new <constructor> }}} [<arg>…]

Configuration
–

Description
Create a new object of a class. Must always be assigned to a variable. Arguments to the constructor must come after the macro, outside the macro context.

Options
–

Operands

• <out_var>: Output variable; the result will be written to this variable.
• <constructor>: A public constructor function.
• <arg>: Arguments for the constructor function, if it takes any.

Stdin
–

Stdout
One line of code is printed, which creates a unique reference and assigns it to <out_var>, and invokes the constructor function.

Stderr
log_error.

Exit status

• 0: Successful completion.
• 1: Bad declaration (abort).

Abort
Any failure will abort the build process. No runtime abort is added.

Usage examples

#{{{
import "{ Array }" from nice_things/collections/Array.sh
#}}}
letters=#{{{ new Array }}} a b c d e